package org.gwt.mosaic.application.client;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Annotation used to simplify <code>Parser's</code> usage.
 * Methods can be annotated using this (they must have a strict syntax, and it is
 * usually a good programming practice to bundle these "resource" elements using an
 * interface (see {@link ResourceConstants})
 * 
 * @author Alex Dobjanschi (alex.dobjanschi@gmail.com)
 *
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ParsedElement {
	
	/**
	 * The location of the file, relative to parser's path.
	 * <br/>
	 * <i>If the file is not found (when {@link #type} is <code>sync</code>), a <code>FileNotFoundException</code> is thrown</i>
	 */
	String file ();
	
	/**
	 * All possible types for this element
	 *
	 */
	enum Types {
		SYNC,
		ASYNC
	}
	
	/**
	 * This specifies how the parser will be used (syncronously - at compile time - or asyncronously - at run time).
	 * <br/>
	 * These types are:
	 * <ul>
	 *    <li> sync = used at compile time</li>
	 *    <li>async = used at run time</li>
	 * </ul>
	 * 
	 * <i>If the type is not supported (or not recognized), a <code>UnsupportedTypeException</code> is thrown</i> 
	 */
	Types type ();
}
